PROGRAM LIBRARY 


□ ECUS NO. 


TITLE 


AUTHOR 


COMPANY 


□ATE 


SOURCE LANGUAGE 


8-595 


UPDATE, A PROGRAM TO MAKE CORRECTIONS 

TO A FILE CONTAINING RECORDS OF VARIABLE LENGTH 

Floor AnthonI and Hons Mees 


Medical Biological Laboratory TNO 
Rijswijk, The Netherlands 


January 5, 1973 


PAL-8 


ATTENTION 


This is a USER program. Other than requiring that it conform to submittal and review standards, 
no quality control has been imposed upon this program by DECUS. 

The DECUS Program Library is a clearing house only; it does not generate or test programs. No 
warranty, express or implied, is made by the contributor. Digital Equipment Computer Users 
Society or Digital Equipment Corporation as to the accuracy or functioning of the program or 
related material, and no responsibility is assumed by these parties in connection therewith. 







PllOUPAM 

NAME 

SOURCE 

LANGUAGE 

AUTHORS 


AliSTPACT 


LIMITATIONS 


PROGRAM 

SIZE 

KQUJJ’MENT AJ:JD 

SOFTWAJU^ 

REQUIRED 


: UPDATE, cl program to make, corrections to a 
file containing records of variable length. 

: PALS 


: Floor Anthoni and Hans Mees, 

Medical Biological Laboratory TNO, 

139, Lange Kleiwog, 

Rijswijk 2100, Tlie NG-therlands. 

: Designed to facilitate the management of data 
such as card-indexes on computer mass-storage 
media, UPDATE provides the user a simple, yet 
powerful means to correct such files by the 
method of string-replacement. The 4K program, 
expanded with the capability of doing PS8 input/ 
output, can easily be adapted to other operating 
environments. 

: The described version needs the PS8 operating 
system. Records are limited to approximately 
700 (10) characters. 

The "commercial AT" sign cannot be used in the 
records. 

: 4K in Field 0 and an additional 10 pages in 
Field 1 . 

: 8K PDP8 running under the 0S8 or PS8 operating 
system. 



CONTENTS 


PAGE 


!. Introduction ^ 

2. UPDATE from the operator's point of view 1 

2.1 Applicability 1 

2.2 The variable length record 1 

2.3 Correction commands. Preparing a correction tape 2 

2.4 Option commands 6 

2.5 Error messages 8 

2.6 Loading, Running and Saving 9 

3. Program Description 9 

3.1 The main program 9 

3.2 The spool program 10 

3.3 Input-output switchability 10 

3.4 PSSIN and PS80UT 10 

3.5 The user module 11 

4. Writing your own USER MODULE 11 

4.1 Adaptability of UPDATE 11 

4.2 Input/Output Routines 12 

4.3 String manipulation routines 13 

4.4 Miscellaneous routines 13 

APPENDIX 1 

Summary of correction commands and special characters 
APPENDIX 2 

Summary of program control options 

APPENDIX 3 

Error messages 

APPENDIX 4 

Survey of routines in UPDATE 

APPENDIX 5 

Core allocation map 

APPENDIX 6 

Program Hierarchy table 



DECUS frogram Library Write-up 


DECUS NO. 8-595 


1, Introduction 

A card-index of all members of a particular organisation is 
a typical example of a small data-"bank". The content of such a 
databank is not constant, with respect to times some members 
leave the organisation, and their entry (their curd) has to be 
deleted from the databank. In other caper, new members have to be 
entered into the card-index, or data of existent members have to 
be changed. These changes are normally done by re-typing the 
respective cardj including all the changes. 

In the shape of a card-index, such data-management can be done 
easily and effectively. 

Problems arise, however, if one tries to ^ something with the 
data: prepare a member’s list, type mailing labels, telephone 

lists, or make selections according to some predetermined proper- 
ties. 

These operations -called "DATA-MAllAGEMENT'' - consume a terrific 
amount of man-power (girl-power), and are the direct reason for 
entering the data into the computer. 

Once transferred into computer format, the data bank is not easily 
accessible as before, unless programs could be developed to faci¬ 
litate the management of computer legible data. 

The program UPDATE is designed to give the secretary an easy 
means to correct her data files. 

The program has a "hole", called the USER MODULE inhere an assem¬ 
bly-written module can use internal routines to perforin the various 
ways of automatic data processing, found in existent data-manage¬ 
ment systems. This makes UPDATE useful for a variety of jobs. 

2. UPDATE from the operator’s point of view 

2.1 Applicability 

In Chapter 1 the idea of data-management was illustrated by an 
example of a card-index of all members of a particular organisation 
with respect to names, addresses, telephone numbers etc. A com- 
plex entry would also containt date of birthj salary group, ami y 
data etc. The applicability of "computerisation" of data extends, 
in general, to all data files that produce a considerable amount 
of type-out, or consume a substantial amount of man-power for auto¬ 
matic type of operations. Examples of data, suitable for UPDATE, 
follow below: 

a) Litterature retrieval data 

b) Descriptive data of-thousands of color slides, films etc. 

c) Vendors of equipment, data 

d) Scientific data files for computer processing 

e) Program development 

f) Program modules:filing and retrieval. 

2.2 The variable length record 

A "record" is a group of data that belongs together. The name, 
of a person, his telephone number, his address are data that belong 
together. The telephone iiumber of someone else, for example, does 
not belong here. The length of one record, expressed in the number 
of characters, is in general not the same for all records. This is 
meant by the term "variable length record". 











The use of fixed length records, where the data elements have to 
appear at certain, pre-determined positions has the disadvantage, 
that the fixed length will in general be chosen to accommodate for 
the longest possible record. A file containing fixed length re¬ 
cords, will in general be substantially longer than a file composed 
of variable length records. A great advantage of fixed length re¬ 
cords is that, when stored on a random-access mass storage device, 
they can be randomly accessed in a fast way. When stored on a se¬ 
quential access mass storage medium (magnetic tape), this advantage 
no longer applies. The program UPDATE was designed for a sequen¬ 
tial access system with records of variable length. An example of 
a variable length record is presented in figure 1. The records n 
need tp be separated by a special marker. This record marker is 
the @ sign in figure 1. 


P0008 

ALPHEM^P.J. VAN A 

A:K00G0VENSJ2H-lb;IJMUIDEN ^ 

T508510-9A893 
l;PROCES AUTOyiAl I SEKING> 

H:PROCESS^ AUlOMATION j PDP8 
90003 

ANTHOMI^ IR. J. F. 
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'1:015-80330-278 (A68) 
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S Y S T E E.y - P h 0 G 'ri A N N t: HEN. 
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Figure 1. 


Another example of a variable length record is the listing of 
UPDATE itself. By inserting the record marker @ at convenient 
places, the program source has been made to resemble a file con¬ 
taining variable length records. 


Note that the @ sign was conveniently chosen because of its in¬ 
frequent use in records. 


2.3 Correction commands. Preparing a correction tape 

There are two classes of commands: 

1) commands that manipulate whole records. These are necessary 
to insert (I), delete (D), append (A) or change (C) a record. 

2) commands that manipulate characters or strings of characters 
within a record, in order to append change insert or delete 
characters. For this purpose a different approach wr.s made, 
in order to facilitate the editing process for the secretary: 
the above mentioned functions are all embedded in the string 
replacement command. 

For example *QICK = QUICK* would be necessary to insert the 
character "u". UPDATE interprets this statement as follows: 
it searches for the first occurrence of the string QICK, de¬ 
letes that string, and inserts the new string QUICK. These 
commands enable us to correct nearly all possible errors in 
the file. The string replacement commands always occur to¬ 
gether with the C (change) command. This informs UPDATE that 
string replacement statements follow. These statements are 
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delimited by a string delimiter character (* in our examples). 

The program UPDATE must in some way recognise on which record a 
certain command has to be effectuated. This is obtained by auto¬ 
matically numbering all records sequentially. UPDATE in fact, in¬ 
serts a four digit number behind every record marker (© that it 
encounters. By doing so, UPDATE adds a property of its own to all 
records in the file, and is therefore unsensitive to the contents 
of each record. By referring to this i nternal record number one 
can direct the command to be effectuated on that single record. 

For example: 0006D would delete record number 0006. Strings of cor¬ 
rections themselves, resemble the structure of a variable-length 
record very much. Therefore the correction strings are separated 
by the same record marker (@) as used in the file. 

@0006D 

@0014A 

THIS IS AN EXAMPLE 

@0015C*QICK=QUICK* 

illustrates the remarkable resemblance to the file of variable length 
records. 

The internal record number can be deleted from or created for all 
files by a program control option (see chapter 2.4). The record 
marker can also be deleted at will. This was necessary to remove 
all properties of UPDATE from the file. 

NOTE that each INSERT, DELETE, or APPEND causes a complete re¬ 
numbering of all subsequent records. During the whole run, however, 
the "old" numbers still apply. A new listing is required to obtain 
the correct, new internal record numbers. 

Let us cycle, for example, through a complete creation and correc¬ 
tion of a file. All typing work can be done at an off-line tele¬ 
type with low speed punch. 

1) Turn on the punch and teletype (LOCAL) and produce some 60 
centimeters of blank tape by pressing the key "HERE IS". 

2 ) 


3) 

4) 


Now the file is entered: 


THIS IS AN EXAMPLE 

(lf) 

THE ou;k brown EOJ. 

JUMPS OVER THE LAZY 

Boc : 

P 

THIS IS A TELETYPE 
P XPQR OHELLO 
@ 

THIS IS THE LAST .RECOHU 
(CTPL/x) 

Produce some 30 centimeters of blank tape by pressing the 
"HERE IS" key, and tear off the tape. 

The internal record numbers are generated by running the pro¬ 
gram UPDATE: 


. leading text is always ignored. 


first "record" 


I 


second "record" 


last "record" 





R UPDATE 


SFRCIl-Y FILES A'xJD OPl I ONS; CORK. TAPE 
ILL.AS<PTh:/I 


put tape in reader; 

IN HSj^» for options ref. 2.4 

the tape reads in. and 
a file FILE.AS is pro¬ 
duced 


5) This file is then listed with PIP: 


.R PIP 

H TTY: <}• ILL. AS/A 
THIS IS AN l.XANPLK 

THE OIIjK BP.OWN P 
JUMPS OVER THE LAZY 
LOG. 
f-fi00P 

THIS IS A TELETYPE 
Q 0 0 0 3 XPOR Q 0 0 0 /! H EL L 0 
000 0 b 

THIS IS THE. LAST HFJCORD 
*■ 


The errors can be corrected by a second run. For easy reference, 
they are underlined. A correction tape is prepared on the off-line 
teletype! 


6) Produce enough blank leader tape. 


THESE ARE COHHEOTIONS 
e0001C+OICK-OUICK* 

*■ POS=i-OX*+:LOC = D0G+ 

(ee) 

(bF) 

V0::'I0PC/A =A UOOE / 
y0003L 

O' ^') 

P00f'ii'iC*H = XF 
H + 

6 000 51 

THIS ht-CORD IS NEARLY 
THE LAST ONE 


(leading text is ignored) 
(corrections, record 0001) 

(line feeds are ignored) 

(insert the word GOOD) 
(record 0003 is too bad) 
(insert aCRin 0004) 

(we want an insert here of) 
(a complete record) 


then finish the tape with enough blank trailer tape. 

7) Run UPDATE to effectuate these corrections 

•■■■ (enter tape in HSR) 

SPECIFY FILES AND OPT I ONSi COF.H. TAPE IN HSR* (for options see 2.4) 
♦FILE.AS<F1LE.AS/C 
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.R PIP 

♦tty:<FILE.AS 
THIS IS AN EKAMIN.,E 

J 

the QUICK BROWN FOX 
JUMPS OVER IKE LAZY 
DOG 
fiOOOP 

THIS IS A GOOD TELETYPE 

G>OO03 

HELLO 

00 00 A 

THIS RECORD IS NEARLY 
THE LAST ONE. 

OO00S 

THIS IS THE LAST RECORD 


A few things can be learnt from the previous example run: 

1) all leading text is ignored, until the first occurrence of 
the record marker. This is true for both the corrections 
and the file. 

2) The string delimiter (*) acts as a sort of switch: it alter¬ 
nates relevant strings and irrelevant strings: A relevant 
string between asterisk number 1 and 2, an irrelevant string 
between asterisk 2 and 3 a relevant between 3 and A, and so on. 
This is the reason that the excessive carriage returns are not 
"seen". 

3) line feeds and blank tape are wholly ignored and can be given 
at any time. 

4) The correction strings can be chosen at will: for example 
@0001C*1=UI**S=X **0C=0G* has the same effect. Remember, 
however, that the program searches for the first occurrence of 
the string to the left of the equal sign. 

5) In records 0001, 0002 the first character is a carriage- 

return. This is not compulsory, as illustrated in record 0003. 
This also counts for the last character. ‘v 

6) The carriage-return is treated as a single character, and can 
be inserted and dele.ted. Additional line feeds can be typed 
to clear up the text. 

7) Most errors are being detected during typing. The rub-out key 
can be used to "rub" successive characters to the left. This 
key gives no echo, but UPDATE takes the appropriate action. 

The back-space pushbutton on the punch is not being used: 

8) The rub-out key does not work past the carriage-return. This 
means that only the characters on the same line, up to the 
left hand margin can be deleted with the rub-out key. The 

key (SHIFT/0) deletes all characters to the left by a single 
strike. These two correction features are effective on all in- 
put to UPDATE. 
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9) The string delimiter (*) can be changed to any character. 

UPDATE takes the first character behind the at the 6th 

position from the record marker, as the string delimiter. The 
same string delimiter must be used throughout the correction 

record. ^ • j k 

10) Correction commands appear in ascending numerical order by 
record number. This is necessary because of the nature of a^^ 
sequential access file. UPDATE can therefore not "step back 

11) A record is always preceded by the record marker (@) and 
terminated by the record marker, or the end of file or end 
ot-tape. 

12) A single @ sign cannot be corrected or deleted. 

13) The HEADER (leading text) cannot be corrected.^ 

14) Corrections to a specific record may be given in one single 
correction record or more records, provided that the same 
record number is referenced. 

for example; @0001C*QICK“QUICK**FOS=FOX* 
is equal to: @0001C*QICK=QUICK* 

@0001C*FOS =F0X* 

15) Corrections can be made to corrections, 
for example: 

@0001C*QICK=QK* (this is obviously not intended) 
@0001C*QK=QUICK* 

The second statement corrects the previous one. 


In order to facilitate the replacement of long strings, like a 
complete line, two string replacement operators can be used: 

"<" and ">". , , 

Xhe "<" operator deletes all characters to the left of the matched 

string, including the matched string. For example the correction 

string 

@0002C*1’YPE<THAT IS MY KEYBOARD* 

Converts the string "THIS IS A TELETYPE" into the string "THAT IS 
MY KEYBOARD" 

The ">" operator works in much the same way. It deletes, however, 
all characters to the right of the matched string, including it. 

It also deletes the carriage-return. The correction string 
@0002C*THIS>* 

deletes the whole line in record 0002. 

Note that the use of these two string operators can save a lot of 
typing. 

2.4 Option commands 

Option commands are' issued to the command-decoder at the time 
the sources and destination should be specified; 

®R UPDATE 

* DESTINATION.AS<S0URCE 1.AS,S0URCE2.AS,'* */O/p/T/l/O/N/S-nnnn 

These options are intended to modify certain functions in the program. 
The options, available in the standard version of UPDATE, follow 
below: 
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/E echoes all input to UPDATE on the teletype. 

This is useful for debugging purposes. 

/F ignores the formfeed character.and deletes it during output. 

/T replaces the tabulation character by an appropriate number 
of spaces. The tabulation interval in 8 characters. 

/C The correction part of UPDATE is used. This option automati" 
cally sets /I and /N for the purpose of rc-numbering the 
records. If /C is not specified, a "short program" will be 
taken. This frees the papertape reader to become a normal 
PS8 input device again. 

/l an internal record number of 4 digits is generated (inserted) 
behind every record marker. 

/N The internal record numbers, or any 4 characters behind the 
record marker are deleted. 

/Z The record markers (@) are deleted. 

/U Gives control to the user module before output is being done 
to the destination. 

=nnnn Label format option. UPDATE groups the record lines into one 
label. If the number of lines is less than nnnn, additional 
carriagc“return/line-feeds will be generated. If the number 
of lines is greater than nnnn, a second label will be formatted 
and additional labels, until the remaining lines fit into the 
last label. Note that octal numbers are accepted onlyJ 

/DIGIT Determines the number of empty lines between each label. When 
more than one digit is entered, the largest one will be obeyed. 

/L Accepts the correction tape from the low speed reader instead 
of the high speed reader. There is, however, no echo. 

NOTE: UPDATE is capable of formatting lines into LABELS. This is use 
i;rr"when type-out on self-sticking labels is preferred, for mailing 
purposes. The options =nnnn and /DIGIT give the user the flexibility 
to adapt the type-out to his specific needs. The use of pinfeed 
paper transport facilities on both printer and labels is a pre¬ 
requisite. 

In practice, not all characters of the ASCII set are being treated 
alike. Some characters have a special function, inherited by both 
the properties of the teletype, and DEC's software. A summary of 
special characters follows below, and the way UPDATE has been made 
to handle them. 

LINEFEED - all line feeds are ignored on all input to UPDATE. 

They are, however, generated for each carriage return 
during output. 

BLANK TAPE - ignored completely 
FORMFEED - ignored only if /F specified. 

after each FOPvMFEED, 10 blanks will be put out. 
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PARITY - The most significant bit of all incoming characters 

(the parity bit) will be set on input and output. 

TABULxMOR - If the tabulation character is followed by a rub-out 
(EDITOR convention), the rub-out will be deleted on 
input. It will however, be re-generated during output. 
If /T was specified, no rub-outs will be put out, and 
tabs are being converted to spaces A TAB without a 
rub-out will also be treated correctly. 

When trying to rub a TAB in off-line correction tape 
preparation one has to strike the RUB OUT key twice. 

SHIFT/C(*’^") • used for off-line tape preparation to delete all 

characters of the current line. This is valid for 
all UPDATE input. 

RECORD MARKER- The @ sign is used for this purpose. Any other cha¬ 
racter can be used by changing location "CAT” and 
"LINEL+12" in the program. The @ acts as string ter¬ 
minator during input. The record marker cannot be 
rubb ed out ! This also counts for each carriage return 
during input. 

">**- used in string replacement statements. See section 


CTRL/Z 


CTRL/C 


2.3. 

- This character is the general PS8 file terminator. It 
also terminates the last record as if it were a record 
marker. The high speed reader routine possesses a 
facility to detect the end-of~tape situation and 
therefore no CTRL/Z is needed to terminate the correct¬ 
ions tape. When using the low speed reader , the last 
character has to be a CTRL/Zl The CTRL/Z is typed 

by holding down the CONTROL key and striking the Z key 

- is the break character to stop program execution and 
return to the monitor immediately. This character is 
obeyed only when issued from the keyboard. The program 
writes the current record away, then exits to the moni^ 
tor. The program is not restartable. 


2.5 Error messages 

In the eyes of the secretary, it is very important that the 
corrections and additions to the database are executed in such a way 
that erroneous data never occur. This can be met by thorough error 
checking in the program. In most cases, the correction command will 
not be executed, and in all cases an error message results. The 
general format of the error message is: 

ERROR MESSAGE AT RRRR FFFF NNNN 

where the error message is in self-explaining English. See Appendix 
3 for a complete summary.. The three numbers refer to the internal 
record numbers at the time that the error occurred. 

RRRR is the number of the correction "record". 

FFFF is the old number of the FILE record. 

NNNN is the new number of the FILE record. 


The new number NNNN enables the operator to repeat the corrections 
that could not be executed. He must therefore prepare a new correct¬ 
ion tape, and refer to the new internal record numbers. The correct¬ 
ions can then be effectuated in a second run. By doing so, one is 
able to prevent the complete typeout of the file in between. 







A second type of error message results from inadvertent use of PS8 
files or devices. These are the USER ERRORS in Appendix 3. 

2.6 Loading, Running and Saving 

The program UPDATE is supplied in two binary tapes, UPDATE.BN 
and PS8I0.BN. The tape PS8I0.BN contains two modules that make PS8 
input/output programming resemble an ordinary teletype. Complete 
documentation is available through DECUS 8-472. The modules have 
been assembled according to the core allocation map in Appendix 4. 

The tape UPDATE.BN contains all UPDATE CODE. To load and save the 
progra"*, proceed as follows: 

R ABSLDR 

iPTR:, PTR: $ (alt mode) 

A-SAVE SYS: UPDATE.SV 

The tapes can be loaded in any order. An example of a complete run 
has been given in section 2.3. 

Section 3.5 illustrates the use of a USER MODULE, and the way a USER 
MODULE can be loaded. The automatic concept, used in the modules 
PS8IN and PS80UT prevents the program from being RESTARTABLE. All 
operations in UPDATE eventually result in a return to monitor. One 
destination (output) file and up to 9 source (input) files can be 
specified to the command decoder. 

3. Program description 

This chapter describes the internal structure and the working 
of the program UPDATE. A complete description of the program would 
be an impossible task. 

However, the design philosophy will be described in the sections of 
this chapter. The reader is referred to the accompanying docuiacnts 
in the appendices for more detail. These are: 

^*1) The program LISTING, produced by the PAL8 assembler. It has 
CROSS REFERENCE tables in the rear. 

** 1) FLOW-CHARTS of the most important program parts. 

3) PROGRAM HIERARCHY TABLE. This tabic, illustrates the hierarchy 
of the program's, internal subroutines. The reader can use this sheet 
to trace which subroutine calls which other subroutine. 

**’4) A BITMAP visualises all locations in core that have been used 
by UPDATE. The user can easily detect small holes in the program for 
small changes. 

5) The CORE ALLOCATION MAP symbolically pictures the location of 
buffers, working-areas, PS8 handlers, etc. in core. 

6) The reader is also referred to chapter 4 where most internal 
subroutines are discussed in more detail. 

3.1 The main program 

The main program of UPDATE has a simple structure. It starts 
printing a message, and reads and w’rites all preceding "Header text 
without processing. This action calls the command decodei through 
PS8IN, where up to 9 sources, one destination and several options may 
be entered. These options are then decoded into specific page zero 
locations: OPTA through OPTZ, LINENO and NOPRINT. If option C has 
been set, the main program will be started. This main program reads 
a correction record and a file record. It compares the record number 
and spools more file records if the record-number of the correction 
record is greater than the record number of the file record. 

* Offered Separately 
** Included with listina oackaae 
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In the case of a match, the next character is read from the correct-ins 
ion record, and used to branch the program to 4 parts: INSERT, Append, 
Change, Delete. Program flow can easily be understood from the flow¬ 
charts, in the case of Ai:'PEND, DELETE and INSERT. The CHANGE part, 
however, is more complex. The next character is taken as the string 
delimiter, and is being deposited in the list CHLIST at the location 
CHTERM. The "match-string" is then isolated. This string always 
occurs between the string delimiter, and the = or < or > sign. The 
File record is then searched from the beginning each time, for a 
match with this string and if found, it will be deleted from the file 
record in the characteristic way of the = and < and > operators. 

The stiing, following the operator (-• <>) is then inserted at that 
point. 

Then the next replacement operation is executed. When all commands 
contained in a correction record have been executed, the program reads 
the next correction record. If the internal correction record number 
still agrees with the internal file record number, then another set 
of correction operations will be executed on the same record. 

Before a record is being written to the output, the option U is tested, 
and if set, control is given to the USER MODULE. In absence of such 
a module, a dummy subroutine returns control to the main program. 

The general output subroutine FORMAT takes care of the execution of 
the options F, I, N, T, Z, DIGIT and =nnnn. 

3.2 The spool program 

In the case the option C has not been set, a very short "spool" 
program is effectuated. This program reads records from the PS8 
sources, and writes them to the PS8 destination. By doing so, the 
papertape reader can be used as an input device. 

All options remain effective in this spool program. 

3.3 Input-Output switchability 

An important feature, employed in UPDATE is the switchability 
of inputs and outputs. All input routines have been written such 
that they exhibit the same properties. Input routines have two sub¬ 
routine returns: one signaling the end-of-tape or end-of-file 
situation, the other is the normal return. After return, the fetched 
character will be in location CHAR. This concept could be realised 
because of the two modules PS8IN and PS80UT that make PS8 behave 
like a Teletype. 

The output routines have been designed in almost the same way, how¬ 
ever, with only one subroutine return. The software switches are 
the locations INDEV and OUTDEV in page 0, that contain a pointer to 
one of the input routines FREAD (from PS8), HREAD (from high speed 
reader) and KEYBD (from keyboard), or one of the output routines 
0UTPS8 (to PS8), PRINT (to' teleprinter) or DUMOUT (which causes no 
output at all). The DUMOUT dummy-routine is used to obscure the 
echo of the input routine LINE, in the case no echo is preferred. 

The user can easily apply his own input and output routines. 

3.4 PS8IN and PS80UT 

The two subroutines PS8IN and PS80UT were designed to make PS8 
look to the programmer as a normal teletype. As PS8 is block-oriented 
with file structured devices, some complex operations have to be 
performed automatically. These can be illustrated by describing the 
actions for the first character, and for the last character (CTRL/Z). 
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A JMS to rS8IN for the first time, calls the command decoder in 
core. It then loads the input device handler in FIELD 0, and 
opens the first input file* The first block is read into an ap¬ 
pointed buffer in FIELD 1, and the first byte is unpacked from it. 

A subroutine return is then taken with the byte in the AC. 

Successive calls to PS8IN deliver successive bytes. If the first 
file is exhausted, the module opens the next one, loading device 
handlers if necessary. The CTRL/Z character, appearing at the 
rear of each input file is ignored, unless it is detected to be 
the last character of the last input file. The CTRL/Z character 
thus n.esignates the absolute end of all input files* The first 
character delivered to PS80UT calls the output handler, and opens 
the output file. Successive characters are packed into the as¬ 
signed output buffer in FIELD 1. Full buffets are being written 
to the output file. 

A CTRL/Z character, sent to PS80UT causes the following actions: 

Tlie CTRL/Z character is packed into the buffer, and the remaining 
space of the output buffer is "padded” with zeroes. The buffer 
is then written to the output file, and the file is closed. A 
direct jump to the MONITOR concludes all actions. 

The tV7o routines are not restartable. Configuration parameters 
with respect to size and location of the buffers, size and locat¬ 
ion of the input- and output handler, and default extension can 
be set at assembly time. 

The modules have proved to be resistant to all possible errors in 
PS8 input/output programming, and produce relevant USER ERROR 
messages. These have been listed in Appendix 3. A complete do¬ 
cumentation can be ordered from the DECUS library (catalogue 
number 8-472). 

3.5 The user module 

The main design philosophy of UPDATE was: flexibility. This 
is reflected in an important feature of UPDATE: a 4 page "hole", 
free for additional code to change interral functions, or for other 
purposes. The hole can be overlaid by a BINARY or IMAGE format 
file. This extends the use of UPDATE to those applications that 
have.not been foreseen by the authors. The USER MODULE is dis¬ 
cussed in more detail in chapter 4. 

4. Writing your own USER MODULE 

The contents of this chapter are intended to instruct the user 
in detail how he can design his USER MODULE by making effective use 
of internal routines within UPDATE. 

The chapter contains, however, useful information for those users 
that want to make some minor modifications to the program. For a 
survey of all useful internal subroutines see Appendix 4. 

4.1 Adaptability of UPDATE 

Much effort has been put in designing UPDATE as flexible as 
could be possible. The authors are aware, however, that the ultimate 
can only be reached by a thorough re-design of UPDATE for which they 
lack time. The adaptability is expressed in the following features: 







1) The presence of a regular 4 page program hole for a USER 
MODULE. 

2) All lists in UPDATE are open-ended, accessible for future 
expansion. 

3) Switchability of inputs and outputs. 

4) A simple string structure: one byte per location; no 
packed bytes in the working areas. 

5) Working areas cannot easily be re-dimensioned during program 
execution, but can be re-defined at assembly time I 

6) Program subroutines can all be used by a USER MODULE. 

7) A .strong hierarchical structure prevents ambiguous situations. 

8) rtll possible options have been decoded in page zero, ready 
to be used by a USER MODULE. 

9) The program is originally designed for 4K operation. All 
that exceeds 4K is the code and buffer areas, necessary to accommo¬ 
date for PS8 input and output facilities. The program can be adapt¬ 
ed for 4K operation under a different operating system. 

10) String manipulation and "garbage collection" is straightfor- 
ward and can easily be understood, 

11) A great part of FIELD 1 is available to the USER. 

12) The number of digits in the internal record number can be 
changed by changing location ZNUM. 

13) The inter-record marker @ can be changed by changing locations 
CAT and LINEL+12. 

14) Locations 0 to 7 have not been used. This is particularly 
useful for debugging purposes. 

15) Users can use several page 0 locations for their modules 
(170-177). 

16) No special programming "tricks" have been used in order to 
save space in core. The code is straight forward and easily under¬ 
standable. 

4.2 Input/Output Routines 

All input routines" were designed to exhibit the same proper¬ 
ties. .Standard input routines (HSREAD, PS8IN) are thereto adapted 
by higher level subroutines. 

These routines (FREAD, HREAD, KEYED) read one character at a time. 
Tliis character is deposited in location CHAR. The parity bit is 
ignored and forced on. When detecting the end-of-file or end-of- 
tape a record marker is transferred into CHAR, and a normal return 
results. The next attempt to read a character, results in an EOT 
return. The subroutine LINE calls the input routines through the 
indirect software switch INDEV. It processes the linefeed, rub- 
out, shift“0, and formfeed characters, and loads the characters into 
a designated core area. It produces an echo for each character, 
back—slashes for rub—outs, etcetera to the output device, pointed 
to by OUTDEV. A carriage—return or a record marker terminates a 
line. 

lie next higher level subroutine GETREC, reads several lines that 
constitute a complete record. The two subroutines on top of GETREC, 
INHSR and INFIL set parameters to read a complete record into its 
specific working area in core. Note that the end-of-file return is 
transferred all the way up, in order to control the flow of the 
main program on the highest level of hierarchy. 

The same sort of organisation rules the output, with the difference 
that the subroutine FORMAT processes and transmits all output on a 
character-by character basis to the output routines. 

.Ml output routines have a normal return only. These routines are 
OUTPS8, PRINT and DUMOUT. Note that 0UTPS8 is a FIELD 0 resident 
routine that calls the FIELD 1 resident output module PS80UT. 
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. 3 String manipulation routines 

Characters are stored one byte per 12 bit location. This 
makes string manipulation easy to understand, and relatively fast. 
The basic search routine is COMPAR. a routine, able to compare two 
strings A and B with a pre-determined length. The routine has 3 
ieturns: for A>B, A-B and A<B. It uses two auto-index pointers 

in page zero; COMPTR for string A and MSPTR for string B. The 
number of characters is entered in the AC. 

The higher level SEARCH routine uses COMPAR. The string in core 
is searched for a match with a string B of predetermined length. 

The search starts with the character, pointed to by AXIN0, and 
proceeds until SCHEND (search end) is reached or a match was found. 
The pointer AXIN0 travels along with the search, and points to the 
beginning of the equivalent of string B in the case a match was 
found. This fact is used by the DELETE and INSERT operators. The 
deletion of for example 4 characters is performed by moving all 
following characters four positions forward. This is the simplest 
way to perform some sort of ''garbage collection . The pointer 
FILEND, pointing to the last character of the string in the FILE 
working area, is corrected. The pointer SCHEND, however, is not 
corrected.' 

ITie pointer AXIN0 and the parameter COUNT 1 determine the DELETE 
action. 

The INSERT function inserts a string at the point AXIN0, by moving 
all following characters backward to create a hole for the string 
to be inserted. The hole is then filled by the insertion string. 
Pointer FILEND is corrected for the new situation. Before an 
INSERT is attempted, the available room in the working area is 
tested. If there is not enough room to perform the INSERT operat¬ 
ion, an error message "RECORD TOO BIG" will be, pHnted while no 
INSERT is performed. 

Note that the pointer SCHEND is not affected I 
4.4 Miscellaneous routine s 

The ERROR MESSAGE routine prints an error message at the 
console Teletype. In addition it prints the internal record numbers 
of the current correction record, of the current file record and 
of the current file record as it is written to the output. If the 
internal record number makes no sense, the four characters ???? 
will be printed instead. For this purpose the internal record 
number itself is replaced by ???? in its working area. 

The BRANCH routine can .be used by user modules to branch the pro¬ 
gram flow through the list look-up technique. 

The INCREMENT routine can be used to count certain events. The 
INCREMENT routine treats an ASCII string of digits as a decimal 
number, and increments that number. The number of digits is deter¬ 
mined by the ACCUMULATOR. The first argument points- to the most 
significant digit of the string. An overflow causes return to 
monitor without any message. 
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The MOVE routine is one of the most frequently used routines I 
it is able to move a block of core memory to a different part 
within 4K. It takes care for the direction of the MOVE in order 
that the block does not overwrite itself. 

The tape "UPDATE SYMBOLS" contains all the necessary definitions 
to design a user module. When assembled in front of the module 
assembly source, and preceded and followed by the XLIST pseudo¬ 
operator it will not be listed in the ultimate listing. 




Al’PENDIX 1 SUMMARY OF CORRECTION COMMANDS 


General syntax examples: 

@00611 THIS IS A NEW RECORD 
e0085D 

@00940 * CORCT=CORRECT **NW = NEW **A:>* 

*-can be any character. However, use it throughout the 

same record. 

A APPEND a record behind the one, numbered here. 

I INSERT this record before the one, numbered here. 

D DELETE this record. 

C CHANGE this record- 


The CHANGE command expects string replacement statements 
of the following type: 


LEFT = 


RIGHT 


LEFT < RIGHT 


Search the string 'LEFT' from the beginning of the 
record. Delete string 'LEFT'. Insert string 'RIGHT' 
at this point. 

Search the string 'LEFT' from the beginning of the 
record. Delete string 'LEFT' and all the preceding 
characters until the left hand margin (previous C.R.) 
Insert string 'RIGHT' at this point. 


LEFT > RIGHT 


Search the string 'LEFT' from the beginning of the 
record. Delete string 'LEFT' and all the following 
characters up to and including the next carriage 
return character. Insert the string 'RIGHT' at this 
point. 












AI’PENDIX 2 SUMMARY OF PROGRAM CONTROL OPTIONS 


Options to be specified to the command decoder. 


/C 


/E 

/F 

/I 

/L 

/N 


/T 

/U 

/Z 

/digit 


=nnnn 


The CORRECTION part of the program is used. The tape 
in the high speed reader is considered to be a correct*- 
ion tape. The records are all re-numbered. 

/C automatically sets /I and /N. 

ECHO all input from high speed reader and PS8 on the 
teletype. Useful for debugging. 

The FORMFEED character is being ignored during input. 

INSERT an INTERNAL RECORD NUMBER behind each occurring 
record marker (@). 

The correction tape is read from the LOW SPEED READER 
(Teletype). 

NO NUMBER ! Deletes the internal record number or any 
four first characters of each record. The use of /l 
and /N together re-numbers the records. 

Replaces TABULATION characters by spaces during output. 

Activates the USER MODULE. 

ZEROES all record markers (@). 

Determines the number of empty lines between labels. 
When typing more than one digit option, the largest one 
will be obeyed. 

Determines the number of lines contained in one label. 
The number is OCTALl If the record contains more lines 
than a label can contain, the remainder will be put on 
a new label and so on. 




APPENDIX 3 ERROR MESSAGES 


General format : 

ERROR MESSAGES AT CCCC FFFF NNNN 

where CCCC ■= the record number of the current correction record 
FFFF » ** ** ** ** ** file ** 

NNNN “ *’ NEW record number of the current file record. 

WRONG SEQUENCE - an attempt has been made to access a record that 
has already been written to the output file. 
Correction ignored. 

ILLEGAI-, COMMND - The first character behind the correction record 

number could not be identified. Correction ignored. 

ILLEGAL SYNTAX ~ Use of string delimiter and string operators in 
string replacement statement is incorrect. Part 
of the correction string could have been executed 
all right. 

STRING NOT FND - The string towards the left of the string operator 
cannot be found. No action is being taken. The 
following string replacement statements may be 
executed all right; Or a command failed to occur 
behind the record number. 

RECORD TOO BIG - The record did not fit into the working area, during 
Insertion or when generating numbers for the first 
time. The insertion is being executed partly. 

ILLEGAL NUMBER - The record number in the correction record was not 
a four digit string. The correction record is 
being ignored. 


PS8IN and PS80UT etror messages are fatal and cause a return to the 
monitor. 


USER ERROR 1 

USER ERROR 2 


USER ERROR 3 
USER ERROR 4 
USER ERROR 5 
USER ERROR 6 


- The output device handler could not be found; an 
attempt was made to load a 2-page handler into 
one page. 

- The output file could not be opened or closed; the 
device was a read-only device; No room for output; 
Two tentative files on this device; An illegal 
device name was specified. 

- No room for output. 

- Write error during output. 

- The input-device handler could not be found. 

- Read error during input. 








APPENDIX 4 SURVEY OF ROUTINES IN UPDATE 


Input/Output routines 

1) Type a character on the Teletype : 

TAD CHARACTER; TYPE (= JMS PRINT); RETURN (AC=0) 

2) Type a CR LF on the Teletype ; 

NEWLIN (= JMS CRLFX); RETURN (AC=0) 

3) Output a character o ver OUTDEV to the output device 

TAD CHARACTER; JMS I OUTDEV; RETURN; AC = 0. Note that the 
output routines are: OUTPS8, PRINT and DUMOUT 

4) Output a CR LF over OUTDEV to the output device; 

CRLF (=JMS FORCR); RETURN (AC=0) 

5) Read a character over INDEV from the input device: 

JMS I INDEV; EOT RETURN; NORMAL RETURN (AC=0) 

Note.'The input routines are KEYED, HPvEAD and FREAD. 

The character is in location CHARI 

6) Read a character from PS8 (0S8): 

GIF 10; JMS PS8IN; RETURN (character in AC) or 
JMS INPS8; RETURN (character in AC) 

7) Read a character from high speed reader ; 

JMS HSPJ:/vD; EOT RETURN; NORMAL RETURl^ (char, in AC) 

8) Read one line of text from INDEV . and echo if 

OPTE' W~. Ignores LF, RUBs following TABs, FORMFEEDS if 
OPTF 0. Back-arrow deletes the line. TAD (INPUTROUTINE; 

DCA INDEV; TAD (OUTPUTROUTINE; DCA OUTDEV; JMS LINE; BUFBEGIN; 
BUFEND; EOT RETURN; NORMAL RETURN 

Both returns with pointer to last character in the AC. 

9) Print a message on the Teletype 

MESG (= JMS PRMESG); ABC, RETURN (AC=0)- 

ABC, TEXT /ABCDEF/ 

String Manipulation Routines 

0 Compare two strings A and B of a pre-determined length. There 
are three returns. 

T/J) (A-1; DCA COMPTR; TAD (B-1; DCA MSPTR; 

TAD (-LENGTH; COMPAR (=JMS COMP); B<A RETURN; 

B>A RETURN; B=A RETURN (AC= 0 in all cases) 

2) Search the working area (FILE BUFFER) from a point, given by 
AXIN0 to an end, given by SCHEND for the occurrence of a string 
STRING . 

TAD ENDPOINTER; DCA SCHEND; TAD BEGIN-1; 

DCA AXIN0; TAD (STRING-l; DCA MSBEG; TAD (-5(length); 

DCA COUNT! ; SEARX (= JMS SEARCH); NOT FOUND RETURN; 

FOUND RETURN; - (in both cases AC=0) 

STRING, "H; "E; "L; "L; "0 

3) Search the current record from its beginning 

for the occurrence of the string ABC. 

SRCHLL (=JMS SRCH); 3; ABC; NOT FOUND RETURN; 

FOUND PJITURN;-(in both cases AC=0) 

ABC, "A; "B; "C 

In case of NOT FOUND return: AXIN0 points to FILEND-3. 

In case of FOUND return: AXIN0 points to the character, 
preceding the found string. 

























4) DELETE a string of length 4 characters starting at the 
location pointed to by AXIN0 + I: 

TAD (4; CIA; DCA COUNTl ; JMS DELETE; RETURN (AC=0) 

5) DELETE the string that was currently searched for 
AX1N0 and COUNT] have been set already, during SEARCHl 
JMS DELETE; RETURN (AC=0) 

6) INSERT a string in the current record, at the position, 
pointed to by AXIN0 

JMS INSRT; + LENGTH; STRING; RETURN (AC=0)- 

STRING, "A; "B; "C - 

7) MOVE a STRING or a block of computer words in core. 

MOVEX (=JMS MOVE); BEGIN OF BLOCK; END OF BLOCK; 

DESTINATION (NEW BEGIN); RETURN (AC=0). 

Miscellaneous routines in Update 

0 Branch routine . It tests the contents of location CHAR against 
a LIST, and jumps to the appropriate address. 

TAD AC; DCA CHAR; BRANX (= JMS BRANCH); LIST-1; 

NOT FOUND RETURIn’ (AC=0)- 

LIST, 212; LF ADDRESS; 215; CR ADDRESS; -; 0 

Note that the list must be terminated by a zero! 

2) Type an error message , the current correction record number, the 
old file record number and the new file record number. 

TAD (MESSAGE; ERPRNT (=JMS ERROR); RETURN (AC=0)- 

MESSAGE, TEXT/18(10) CHARACTERS/ 

increment an ASCII string of digits as if it were one decimal 
number. The accu contains - number of digits. 

TAD (-4; JMS INC10; NUM; RETURN (AC=0)- 

NUM, 260; 261; 262; 263 /The number 0123 becomes 0124. 

4) Test the keyboard for CTRL/C 

TESTC (=JMS CTRLC); RETURN.(AC=0) 

Detection of the CTRL/C character causes an immediate return to 
the MONITOR. 
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APPEMDIX 5 - CORE ALLOCATION 


FIELD 0 



7600 

7600 

7200 

• 7400 

6600 

7200 


6200 


5200 


5200 


3400 


2400 


0000 


2000 


FIELD 2 


MONITOR 


PS8IN 


PS80UT 


OUTPUTBUF 


INPUTBUF 


0000 


USER 
SERVICE 
ROUTINES 
SWAPPED 
IN AND OUT 





























APPENDIX 6 UPDATE PROGfRAH HIERARCHY 






















































































































































































